// =============================================================================
//  STATS - Statistical Analysis Tools, v.0.01
//  Copyright (C) 2012  Marco Vettigli
// -----------------------------------------------------------------------------
//
// This program  is free software:  you can  redistribute it and/or  modify it
// under the terms of the  GNU General Public License as published by the Free
// Software Foundation,  either version 3 of the License,  or (at your option)
// any later version.
//
// This program is distributed in the hope that it will be useful, but WITHOUT
// ANY WARRANTY;  without even  the  implied  warranty  of  MERCHANTABILITY or
// FITNESS FOR A PARTICULAR PURPOSE.  See the  GNU General Public License  for
// more details.
//
// You  should  have received a copy of the  GNU General Public License  along
// with this program.  If not, see <http://www.gnu.org/licenses/>.
//
// =============================================================================
//
// UTILS.H
// The class contains several utility function to handle data analysis and
// manipulation.
//
// Author: Marco Vettigli
//
// =============================================================================

#ifndef UTILS_H
#define UTILS_H

// == include directives =======================================================

#include <QVector>
#include <QString>
#include <QChar>
#include "stable.h"

// == class definitions ========================================================

namespace StatS {

class Utils
{

public:

// == constructors and destructors =============================================

// == getters ==================================================================

// == setters ==================================================================

// == inspectors ===============================================================

// == accessor function declarations ===========================================

    // -- public ---------------------------------------------------------------
    // StatS::Utils::parseCSV(const QString, QChar, QChar, bool)
    //
    // The function parses a CSV file in new STable given 'filename' path,
    // delimiter and quoting character. If 'firstNames' is true, first row will
    // be used for column naming. Column content will be automatically
    // checked for type convertion.
    //
    // -------------------------------------------------------------------------
    static StatS::STable* parseCsv(const QString filename,
                                   QChar delimiter,
                                   QChar quotes,
                                   bool firstNames);

    // -- public ---------------------------------------------------------------
    // StatS::Utils::parseStatS(const QString)
    //
    // The function parses a StatS file (.stats) in a new STable, given
    // 'filename' path. If file is corrupted or not parsable, 0 pointer is
    // returned.
    //
    // -------------------------------------------------------------------------
    static StatS::STable* parseStatS(const QString filename);

    // -- public ---------------------------------------------------------------
    // StatS::Utils::parseClipboard(QVector<QVector<QString>>&, const QString&)
    //
    // The function parses tabular data in form of string 'clipboard' using
    // tab and endline characters to define columns and rows. Parsed data are
    // retrieved in 'table' QVector of QVectors of QStrings.
    //
    // -------------------------------------------------------------------------
    static bool parseClipboard(QVector<QVector<QString> >& table,
                               const QString& clipboard);

    // -- public ---------------------------------------------------------------
    // StatS::Utils::getPairNumber(SDoubles*, SDoubles*)
    //
    // Function to get the number of not-null pairs present in two SDoubles
    // array. Array sizes must be equal for computation to take place, if not
    // so the function will return -1.
    //
    // -------------------------------------------------------------------------
    static int getPairNumber(StatS::SDoubles* array1,
                             StatS::SDoubles* array2);

    // -- public ---------------------------------------------------------------
    // StatS::Utils::getRangeList(int, int)
    //
    // The function returns a list of integers spanning from number 'from' to
    // number 'to'.
    //
    // -------------------------------------------------------------------------
    static QList<int> getRangeList(int to,
                                   int from);

// == variable declarations ====================================================

// == private function declarations ============================================

private:

    // -- private --------------------------------------------------------------
    // StatS::Utils::parseLine(QVector<QString>&, QString&, QChar, QChar)
    //
    // Aid function to parse a single line at once returning in 'parsed_line'
    // the tokens defined by 'delimiter' and 'quotes'. The function need a
    // string 'line' as source and returns number of parsed tokens.
    //
    // -------------------------------------------------------------------------
    static int parseLine(QVector<QString>& parsed_line,
                         QString& line,
                         QChar delimiter,
                         QChar quotes);

    // -- private --------------------------------------------------------------
    // StatS::Utils::parsePropertyLine(QVector<QString>&, QString&)
    //
    // Aid function to parse a single line containing property tokens. A
    // property token is eclosed in brackets('{' and '}') and separated by
    // colons. These tokens are returned back in parsed_line as a QVector of
    // QStrings. The function returns the number of parsed tokens too.
    //
    // -------------------------------------------------------------------------
    static int parsePropertyLine(QVector<QString>& parsed_line,                                 
                                 QString& line);

};

}

#endif // UTILS_H
